Supported with v3.0.0+

The Dice Roller Widget is a widget you can add to your game to easily add dice rolling support, from the middle of the screen or from the user's drawer position.

This widget assumes the project has the standard gravity set within your project.

For any user support, the widget assumes the camera is set in a way where the edges of the dice roller match up with the edges of the screen to allow the dice rolls to come from the user's drawer location.

You can add the Dice Roller Widget through the Gameboard menu options at Gameboard > Tool > Add Dice Roller Widget

*WARNING* This will modify your camera settings to line up with the widget. If you don't want this to happen, the prefab can be found in Package > Gameboard Unity Plugin > Runtime > Tools > Prefabs > DiceRoller.prefab

This will add the gameboard SDK (if it doesn't already exist) and align the camera to support the user dice rolling, so the dice would roll from the user's drawer location.

Now that you have the prefab pulled into your project, you're presented with a few options to customize the dice widget.

• Dice Spawn Location
  • If you don't supply a camera, this is the location that the dice will roll when the RollDice method is called. If a camera is supplied, the dice will be rolled in the middle of the camera view from Spawn Distance from Camera away from the camera.
• Game Camera
  • Camera looking down in the standard board manner. Required when using RollDiceForUser method or if the Touch To Move Dice option is true.
• Spawn Distance from Camera
  • How far from the camera the dice generate when a camera is supplied.
• Dice Scale
  • Allows you to adjust how large you would like the dice generated to be.
• Touch To Move Dice
  • Adds colliders to move the dice when touching/dragging on the screen. (Does not allow picking up dice, just touching the board will cause collision with the dice)
• Include Companion support
  • Automatically show the dice selector when user's join with the specified dice sizes in the DicePrefabs.
• Use Bounding Box
  • If true, uses the existing bounds in the prefab. (The bounds default to the camera bounds set with gameboard's AlignCameraForGameboard) Otherwise, disables them so you can create your own colliders.
• Dice Prefabs list
  • List of dice available to roll. You can create your own GameboardDice to add/remove which dice are available to roll.

Now that you have your dice roller configured, you will want to start rolling dice. For all of the methods the allowing rolling and modifying the dice, there are two events that will be important to listen to:

• DiceRollCompleted: This event is triggered when the dice are done rolling around and returns the total of all the dice on the board currently
• DiceRollTotalChanged: This event is triggered any time the dice total is changed, either through rolling dice or removing dice. This also returns the total of all the dice on the board currently.

void Start()
{
    roller.DiceRollCompleted += RollComplete;
    roller.DiceRollTotalChanged += RollValueChanged;
}

void RollComplete(int result)
{
    // result after roll
}

void RollValueChanged(int result)
{
    // result after any change (roll, clear dice, etc)
}

There are a few methods available that you can use to roll dice depending on how you have configured your dice roller.

RollDice(int[] diceSizes)

• Rolls dice in the bounding box. If a game camera is specified, the dice will roll in the middle of the screen the specified distance from the camera. If not specified, the dice will spawn at the DiceSpawnLocation gameObject.
  • (params) diceSizes - an array containing the sizes of dice you want to roll. i.e if you want to roll two d6s and a d20, you would send [6, 6, 20].
  • (returns) Nothing. To get the result of the roll, you must listen to either DiceRollCompleted or DiceRollTotalChanged

  //Rolls a d4, two d6s, a d8, d10, and d20
  roller.RollDice(new int[7] { 4, 6, 6, 8, 10, 12, 20 });
  

RollDiceForUser(int[] diceSizes, string userId)

• Rolls dice from the location of a user's player drawer. This requires a game camera to be specified. If using the bounding box, make sure it is properly aligned with your camera view to prevent unwanted collisions.
  • (params) diceSizes - an array containing the sizes of dice you want to roll. i.e if you want to roll three d6s and a d20, you would send [6, 6, 6, 20].
  • (params) userId - string indicating userId for the user you would like to show rolling the above dice sizes
  • (returns) Nothing. To get the result of the roll, you must listen to either DiceRollCompleted or DiceRollTotalChanged. They return the total of all the dice on the board, to get the total for the specific user, you can look at the CurrentTotalForUser dictionary with CurrentTotalForUser[{userId}] to get the total for that user. Or if you want to see the individual dice for that user, you can look at the CurrentDiceForUser dictionary.

  // Rolls two d6s for the user of that userPresence object
  roller.RollDiceForUser(new int[2] { 6, 6 }, userPresence.userId);
  

ReRollCurrentDice()

• Rerolls all current dice.

  roller.ReRollCurrentDice();

ClearDice()

• Removes all current dice from the roller.

  roller.ClearDice();

ClearDiceForUser(string userId)

• Removes dice rolled for specific userId
  • (params) userId - string indicatin userId for user you would like to remove the dice of.

  roller.ClearDiceForUser(userPresence.userId);

The Dice Roller will roll GameboardDice. You can create your own dice if they inherit from the GameboardDice object. GameboardDice will have the following usefil properties:

• Size: The number of sides. For a 20 sided die, this would be 20.
• CurrentValue: Current side of the die that is facing upwards.
• id: Id of the die if wanting to set a unique identifier.
• Name: Name of the die to appear in the companion app, if applicable.
• IsRolling: If the current die's Rigidbody is still in motion.

There are also some useful methods that can be used on the GameboardDice object:

• GetSideValueFacingUp() - returns an int indicating the current side that is facing upwards.
• Roll(Vector3 direction) - rolls the die. You can pass in an optional Vector3 indicating the direction you would like the die to roll in.
• ReRoll(Vector3 direction) - rerolls the die. You can pass in an optional Vector3 indicating the direction you would like the die to roll in.
• PrepareRoll() - sets the initial position of the die to reset to when rerolling the die.

Each GameboardDice also has it's own event called RollCompleted that you can listen to if you want to perform actions based on specific die rolls. That event returns the GameboardDice object that was rolled, and the int result of that roll.

This section include the entire code in one single, easy to copy section.

public GameboardDiceRoller roller;
private UserPresenceController userPresenceController;

void Start()
{
    GameObject gameboardObject = GameObject.FindWithTag("Gameboard");

    roller.DiceRollCompleted += RollComplete;
    roller.DiceRollTotalChanged += RollValueChanged;

    userPresenceController = gameboardObject.GetComponent<UserPresenceController>();
    userPresenceController.OnUserPresence += OnUserPresence;
}

void RollComplete(int result)
{
    // result after roll
}

void RollValueChanged(int result)
{
    // result after any change (roll, clear dice, etc)
}

public void RollDice()
{
    roller.RollDice(new int[7] { 4, 6, 6, 8, 10, 12, 20 });
}

public void ReRollCurrentDice()
{
    roller.ReRollCurrentDice();
}

public void ClearDice()
{
    roller.ClearDice();
}

private void OnUserPresence(GameboardUserPresenceEventArgs userPresence)
{
    switch (userPresence.changeValue)
    {
        case DataTypes.UserPresenceChangeTypes.REMOVE:
            roller.ClearDiceForUser(userPresence.userId);
            break;
        case DataTypes.UserPresenceChangeTypes.CHANGE_POSITION:
        case DataTypes.UserPresenceChangeTypes.CHANGE:
            roller.RollDiceForUser(new int[2] { 6, 6 }, userPresence.userId);
            break;
    }
}